   This is an introduction to `Programming in Emacs Lisp', for people
who are not programmers.

   Edition 1.05, 21 October 1997

   Copyright (C) 1990, '91, '92, '93, '94, '95, '97 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

The `progn' Function
--------------------

   `progn' is a function that causes each of its arguments to be
evaluated in sequence and then returns the value of the last one.  The
preceding expressions are evaluated only for the side effects they
perform.  The values produced by them are discarded.

   The template for a `progn' expression is very simple:

     (progn
       BODY...)

   In `zap-to-char', the `progn' expression has to do two things: put
point in exactly the right position; and return the location of point
so that `kill-region' will know how far to kill to.

   The first argument to the `progn' is `search-forward'.  When
`search-forward' finds the string, the function leaves point
immediately after the last character in the target string.  (In this
case the target string is just one character long.)  If the search is
backwards, `search-forward' leaves point just before the first
character in the target.  The movement of point is a side effect.

   The second and last argument to `progn' is the expression `(point)'.
This expression returns the value of point, which in this case will be
the location to which it has been moved by `search-forward'.  This
value is returned by the `progn' expression and is passed to
`kill-region' as `kill-region''s second argument.

Summing up `zap-to-char'
------------------------

   Now that we have seen how `search-forward' and `progn' work, we can
see how the `zap-to-char' function works as a whole.

   The first argument to `kill-region' is the position of the cursor
when the `zap-to-char' command is given--the value of point at that
time.  Within the `progn', the search function then moves point to just
after the zapped-to-character and `point' returns the value of this
location.  The `kill-region' function puts together these two values of
point, the first one as the beginning of the region and the second one
as the end of the region, and removes the region.

   The `progn' function is necessary because the `kill-region' command
takes two arguments; and it would fail if `search-forward' and `point'
expressions were  written in sequence as two additional arguments.  The
`progn' expression is a single argument to `kill-region' and returns
the one value that `kill-region' needs for its second argument.

The Version 18 Implementation
-----------------------------

   The version 18 implementation of `zap-to-char' is slightly different
from the version 19 implementation: it zaps the text up to but not
including the zapped-to-character; and zaps to the end of the buffer if
the specified character is not found.

   The difference is in the second argument to the `kill-region'
command.  Where the version 19 implementation looks like this:

     (progn
       (search-forward (char-to-string char) nil nil arg)
       (point))

The version 18 implementation looks like this:

     (if (search-forward (char-to-string char) nil t arg)
         (progn (goto-char
                 (if (> arg 0) (1- (point)) (1+ (point))))
                (point))
       (if (> arg 0)
           (point-max)
         (point-min)))

   This looks considerably more complicated, but the code can be readily
understood if it is looked at part by part.

   The first part is:

     (if (search-forward (char-to-string char) nil t arg)

This fits into an `if' expression that does the following job, as we
shall see:

     (if ABLE-TO-LOCATE-ZAPPED-FOR-CHARACTER-AND-MOVE-POINT-TO-IT
         THEN-MOVE-POINT-TO-THE-EXACT-SPOT-AND-RETURN-THIS-LOCATION
        ELSE-MOVE-TO-END-OF-BUFFER-AND-RETURN-THAT-LOCATION)

Evaluation of the `if' expression specifies the second argument to
`kill-region'.  Since the first argument is point, this process makes
it possible for `kill-region' to remove the text between point and the
zapped-to location.

   We have already described how `search-forward' moves point as a side
effect.  The value that `search-forward' returns is `t' if the search
is successful and either `nil' or an error message depending on the
value of the third argument to `search-forward'.  In this case, `t' is
the third argument and it causes the function to return `nil' when the
search fails.  As we will see, it is easy to write the code for
handling the case when the search returns `nil'.

   In the version 18 implementation of `zap-to-char', the search takes
place because the `if' causes the search expression to be evaluated as
its true-or-false-test.  If the search is successful, Emacs evaluates
the then-part of the `if' expression.  On the other hand, if the search
fails, Emacs evaluates the else-part of the `if' expression.

   In the `if' expression, when the search succeeds, a `progn'
expression is executed--which is to say, it is run as a program.

   As we said earlier, `progn' is a function that causes each of its
arguments to be evaluated in sequence and then returns the value of the
last one.  The preceding expressions are evaluated only for the side
effects they perform.  The values produced by them are discarded.

   In this version of `zap-to-char', the `progn' expression is executed
when the `search-forward' function finds the character for which it is
searching.  The `progn' expression has to do two things: put point in
exactly the right position; and return the location of point so that
`kill-region' will know how far to kill to.

   The reason for all the code in the `progn' is that when
`search-forward' finds the string it is looking for, it leaves point
immediately after the last character in the target string.  (In this
case the target string is just one character long.)  If the search is
backwards, `search-forward' leaves point just before the first
character in the target.

   However, this version of the `zap-to-char' function is designed so
that it does not remove the character being zapped to.  For example, if
`zap-to-char' is to remove all the text up to a `z', this version will
not remove the `z' as well.  So point has to be moved just enough that
the zapped-to character is not removed.

The body of the `progn' expression
..................................

   The body of the `progn' consists of two expressions.  Spread out to
delineate the different parts more clearly, and with comments added, the
`progn' expression looks like this:

     (progn

       (goto-char                ; First expression in `progn'.
             (if (> arg 0)       ; If `arg' is positive,
                 (1- (point))    ;   move back one character;
               (1+ (point))))    ;   else move forward one character.

       (point))                  ; Second expression in `progn':
                                 ;   return position of point.

The `progn' expression does this: when the search is forward (`arg' is
positive), Emacs leaves point just after the searched-for character.
By moving point back one position, the character is uncovered.  In this
case, the expression in the `progn' reads as follows: `(goto-char (1-
(point)))'.  This moves point one character back.  (The `1-' function
subtracts one from its argument, just as `1+' adds ones to its
argument.)  On the other hand, if the argument to `zap-to-character' is
negative, the search will be backwards.  The `if' detects this and the
expression reads: `(goto-char (1+ (point)))'.  (The `1+' function adds
one to its argument.)

   The second and last argument to `progn' is the expression `(point)'.
This expression returns the value of the position to which point is
moved by the first argument to `progn'.  This value is then returned by
the `if' expression of which it is a part and is passed to
`kill-region' as `kill-region''s second argument.

   In brief, the function works like this: the first argument to
`kill-region' is the position of the cursor when the `zap-to-char'
command is given--the value of point at that time.  The search function
then moves point if the search is successful.  The `progn' expression
moves point just enough so the zapped to character is not removed, and
returns the value of point after all this is done.  The `kill-region'
function then removes the region.

   Finally, the else-part of the `if' expression takes care of the
situation in which the zapped-towards character is not found.  If the
argument to the `zap-to-char' function is positive (or if none is
given) and the zapped-to character is not found, all the text is
removed from the current position of point to the end of the accessible
region of the buffer (the end of the buffer if there is no narrowing).
If the `arg' is negative and the zapped-to character is not found, the
operation goes to the beginning of the accessible region.  The code for
this is a simple `if' clause:

     (if (> arg 0) (point-max) (point-min))

   This says that if `arg' is a positive number, return the value of
`point-max', otherwise, return the value of `point-min'.

   For review, here is the code involving `kill-region', with comments:

     (kill-region
      (point)                    ; beginning-of-region
      (if (search-forward
           (char-to-string char) ; target
           nil                   ; limit-of-search: none
           t                     ; Return `nil' if fail.
           arg)                  ; repeat-count.
          (progn                 ; then-part
            (goto-char
             (if (> arg 0)
                 (1- (point))
               (1+ (point))))
            (point))

        (if (> arg 0)            ; else-part
            (point-max)
          (point-min))))

   As you can see, the version 19 implementation does slightly less
than the version 18 implementation, but is much simpler.

`kill-region'
=============

   The `zap-to-char' function uses the `kill-region' function.  This
function is very simple; leaving out part of its documentation string,
it looks like this:

     (defun kill-region (beg end)
       "Kill between point and mark.
     The text is deleted but saved in the kill ring."
       (interactive "*r")
       (copy-region-as-kill beg end)
       (delete-region beg end))

   The main point to note is that it uses the `delete-region' and
`copy-region-as-kill' functions which are described in following
sections.

`delete-region': A Digression into C
====================================

   The `zap-to-char' command uses the `kill-region' function, which in
turn uses two other functions, `copy-region-as-kill' and
`delete-region'.  The `copy-region-as-kill' function will be described
in a following section; it puts a copy of the region in the kill ring
so it can be yanked back.  (see `copy-region-as-kill'.)

   The `delete-region' function removes the contents of a region and
you cannot get it back.

   Unlike the other code discussed here, `delete-region' is not written
in Emacs Lisp; it is written in C and is one of the primitives of the
GNU Emacs system.  Since it is very simple, I will digress briefly from
Lisp and describe it here.

   Like many of the other Emacs primitives, `delete-region' is written
as an instance of a C macro, a macro being a template for code.  The
first section of the macro looks like this:

     DEFUN ("delete-region", Fdelete_region, Sdelete_region, 2, 2, "r",
       "Delete the text between point and mark.\n\
     When called from a program, expects two arguments,\n\
     character numbers specifying the stretch to be deleted.")

   Without getting into the details of the macro writing process, let me
point out that this macro starts with the word `DEFUN'.  The word
`DEFUN' was chosen since the code serves the same purpose as `defun'
does in Lisp.  The word `DEFUN' is followed by seven parts inside of
parentheses:

   * The first part is the name given to the function in Lisp,  in this
     case, `delete-region'.

   * The second part is the name of the function in C, `Fdelete_region'.
     By convention, it starts with `F'.  Since C does not use hyphens
     in names, an underscore is used instead.

   * The third part is the name for the C constant structure that
     records information on this function for internal use.  It is the
     name of the function in C but begins with an `S' instead of an `F'.

   * The fourth and fifth parts specify the minimum and maximum number
     of arguments the function can have.  In this case, the function
     demands exactly 2 arguments.

   * The sixth part is just like the argument that follows the
     `interactive' declaration in a function written in Lisp: a letter
     followed, perhaps, by a prompt.  In this case, the letter is `"r"'
     which indicates that the two arguments to the function will be the
     position of the beginning and end of a region in the buffer.  In
     this code, there isn't any prompt.

   * The seventh part is a documentation string, just like the one for a
     function written in Emacs Lisp, except that every newline must be
     written explicitly as `\n' followed by a backslash and carriage
     return.

   The formal parameters come next, with a statement of what kind of
object they are, and then what might be called the `body' of the macro.
For `delete-region' the `body' consists of the following three lines:

     validate_region (&b, &e);
     del_range (XINT (b), XINT (e));
     return Qnil;

   The first function, `validate_region' checks whether the values
passed as the beginning and end of the region are the proper type and
are within range.  The second function, `del_range', actually deletes
the text.  If the function completes its work without error, the third
line returns `Qnil' to indicate this.

   `del_range' is a complex function we will not look into.  It updates
the buffer and does other things.  However, it is worth looking at the
two arguments passed to `del_range'.  These are `XINT (b)' and
`XINT (e)'.  As far as the C language is concerned, `b' and `e' are two
thirty-two bit integers that mark the beginning and end of the region
to be deleted.  But like other numbers in Emacs Lisp, only twenty-four
bits of the thirty-two bits are used for the number; the remaining
eight bits are used for keeping track of the type of information and
other purposes.  (On certain machines, only six bits are so used.)  In
this case, the eight bits are used to indicate that these numbers are
for buffer positions.  When bits of a number are used this way, they
are called a "tag".  The use of the eight bit tag on each thirty-two
bit integer made it possible to write Emacs to run much faster than it
would otherwise.  On the other hand, with numbers limited to
twenty-four bits, Emacs buffers are limited to approximately eight
megabytes.  (You can sharply increase the maximum buffer size by adding
defines for `VALBITS' and `GCTYPEBITS' in the `emacs/src/config.h' file
before compiling.  See the note in the `emacs/etc/FAQ' file that is
part of the Emacs distribution.)

   `XINT' is a C macro that extracts the 24 bit number from the
thirty-two bit Lisp object; the eight bits used for other purposes are
discarded.  So `del_range (XINT (b), XINT (e))' deletes the region
between the beginning position, `b', and the ending position, `e'.

   From the point of view of the person writing Lisp, Emacs is all very
simple; but hidden underneath is a great deal of complexity to make it
all work.

Initializing a Variable with `defvar'
=====================================

   Unlike the `delete-region' function, the `copy-region-as-kill'
function is written in Emacs Lisp.  It copies a region in a buffer and
saves it in a variable called the `kill-ring'.  This section describes
how this variable is created and initialized.

   (Again we note that the term `kill-ring' is a misnomer.  The text
that is clipped out of the buffer can be brought back; it is not a ring
of corpses, but a ring of resurrectable text.)

   In Emacs Lisp, a variable such as the `kill-ring' is created and
given an initial value by using the `defvar' special form.  The name
comes from "define variable".

   The `defvar' special form is similar to `setq' in that it sets the
value of a variable.  It is unlike `setq' in two ways: first, it only
sets the value of the variable if the variable does not already have a
value.  If the variable already has a value, `defvar' does not override
the existing value.  Second, `defvar' has a documentation string.

   You can see the current value of a variable, any variable, by using
the `describe-variable' function, which is usually invoked by typing
`C-h v'.  If you type `C-h v' and then `kill-ring' (followed by <RET>)
when prompted, you will see what is in your current kill ring--this may
be quite a lot!  Conversely, if you have been doing nothing this Emacs
session except read this document, you may have nothing in it.  At the
end of the `*Help*' buffer, you will see the documentation for
`kill-ring':

     Documentation:
     List of killed text sequences.

   The kill ring is defined by a `defvar' in the following way:

     (defvar kill-ring nil
       "List of killed text sequences.")

In this variable definition, the variable is given an initial value of
`nil', which makes sense, since if you have saved nothing, you want
nothing back if you give a `yank' command.  The documentation string is
written just like the documentation string of a `defun'.  As with the
documentation string of the `defun', the first line of the
documentation should be a complete sentence, since some commands, like
`apropos', print only the first line of documentation.  Succeeding
lines should not be indented; otherwise they look odd when you use `C-h
v' (`describe-variable').

   Most variables are internal to Emacs, but some are intended as
options that you can readily set with the `edit-options' command.
(These settings last only for the duration of an editing session; to
set a value permanently, write a `.emacs' file.  See Your `.emacs' File.)

   A readily settable variable is distinguished from others in Emacs by
an asterisk, `*', in the first column of its documentation string.

   For example:

     (defvar line-number-mode nil
       "*Non-nil means display line number in mode line.")

This means that you can use the `edit-options' command to change the
value of `line-number-mode'.

   Of course, you can also change the value of `line-number-mode' by
evaluating it within a `setq' expression, like this:

     (setq line-number-mode t)

See Using `setq'.

`copy-region-as-kill'
=====================

   The `copy-region-as-kill' function copies a region of text from a
buffer and saves it in a variable called the `kill-ring'.

   If you call `copy-region-as-kill' immediately after a `kill-region'
command, Emacs appends the newly copied text to the previously copied
text.  This means that if you yank back the text, you get it all, from
both this and the previous operation.  On the other hand, if some other
command precedes the `copy-region-as-kill', the function copies the
text into a separate entry in the kill ring.

   Here is the complete text of the version 18 `copy-region-as-kill',
formatted for clarity with several comments added:

     (defun copy-region-as-kill (beg end)
       "Save the region as if killed, but don't kill it."
       (interactive "r")

       (if (eq last-command 'kill-region)

           ;; then-part: Combine newly copied text
           ;;   with previously copied text.
           (kill-append (buffer-substring beg end) (< end beg))

         ;; else-part: Add newly copied text as a new element
         ;;   to the kill ring and shorten the kill ring if necessary.
         (setq kill-ring
               (cons (buffer-substring beg end) kill-ring))
         (if (> (length kill-ring) kill-ring-max)
             (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))

       (setq this-command 'kill-region)
       (setq kill-ring-yank-pointer kill-ring))

   As usual, this function can be divided into its component parts:

     (defun copy-region-as-kill (ARGUMENT-LIST)
       "DOCUMENTATION..."
       (interactive "r")
       BODY...)

   The arguments are `beg' and `end' and the function is interactive
with `"r"', so the two arguments must refer to the beginning and end of
the region.  If you have been reading though this document from the
beginning, understanding these parts of a function is almost becoming
routine.

   The documentation is somewhat confusing unless you remember that the
word `kill' has a meaning different from its usual meaning.

   The body of the function starts with an `if' clause.  What this
clause does is distinguish between two different situations: whether or
not this command is executed immediately after a previous `kill-region'
command.  In the first case, the new region is appended to the
previously copied text.  Otherwise, it is inserted into the beginning
of the kill ring as a separate piece of text from the previous piece.

   The last two lines of the function are two `setq' expressions.  One
of them sets the variable `this-command' to `kill-region' and the other
sets the variable `kill-ring-yank-pointer' to point to the kill ring.

   The body of `copy-region-as-kill' merits discussion in detail.

The Body of `copy-region-as-kill'
---------------------------------

   The `copy-region-as-kill' function is written so that two or more
kills in a row combine their text into a single entry.  If you yank back
the text from the kill ring, you get it all in one piece.  Moreover,
kills that kill forward from the current position of the cursor are
added to the end of the previously copied text and commands that copy
text backwards add it to the beginning of the previously copied text.
This way, the words in the text stay in the proper order.

   The function makes use of two variables that keep track of the
current and previous Emacs command.  The two variables are
`this-command' and `last-command'.

   Normally, whenever a function is executed, Emacs sets the value of
`this-command' to the function being executed (which in this case would
be `copy-region-as-kill').  At the same time, Emacs sets the value of
`last-command' to the previous value of `this-command'.  However, the
`copy-region-as-kill' command is different; it sets the value of
`this-command' to `kill-region', which is the name of the function that
calls `copy-region-as-kill'.

   In the first part of the body of the `copy-region-as-kill' function,
an `if' expression determines whether the value of `last-command' is
`kill-region'.  If so, the then-part of the `if' expression is
evaluated; it uses the `kill-append' function to concatenate the text
copied at this call to the function with the text already in the first
element (the CAR) of the kill ring.  On the other hand, if the value of
`last-command' is not `kill-region', then the `copy-region-as-kill'
function attaches a new element to the kill ring.

   The `if' expression reads as follows; it uses `eq', which is a
function we have not yet seen:

     (if (eq last-command 'kill-region)
         ;; then-part
         (kill-append (buffer-substring beg end) (< end beg))

The `eq' function tests whether its first argument is the same Lisp
object as its second argument.  The `eq' function is similar to the
`equal' function in that it is used to test for equality, but differs
in that it determines whether two representations are actually the same
object inside the computer, but with different names.  `equal'
determines whether the structure and contents of two expressions are
the same.

The `kill-append' function
..........................

   The `kill-append' function looks like this:

     (defun kill-append (string before-p)
       (setcar kill-ring
               (if before-p
                   (concat string (car kill-ring))
                   (concat (car kill-ring) string))))

   We can look at this function in parts.  The `setcar' function uses
`concat' to concatenate the new text to the CAR of the kill ring.
Whether it prepends or appends the text depends on the results of an
`if' expression:

     (if before-p                            ; if-part
         (concat string (car kill-ring))     ; then-part
       (concat (car kill-ring) string))      ; else-part

If the region being killed is before the region that was killed in the
last command, then it should be prepended before the material that was
saved in the previous kill; and conversely, if the killed text follows
what was just killed, it should be appended after the previous text.
The `if' expression depends on the predicate `before-p' to decide
whether the newly saved text should be put before or after the
previously saved text.

   The symbol `before-p' is the name of one of the arguments to
`kill-append'.  When the `kill-append' function is evaluated, it is
bound to the value returned by evaluating the actual argument.  In this
case, this is the expression `(< end beg)'.  This expression does not
directly determine whether the killed text in this command is located
before or after the kill text of the last command; what is does is
determine whether the value of the variable `end' is less than the
value of the variable `beg'.  If it is, it means that the user is most
likely heading towards the beginning of the buffer.  Also, the result
of evaluating the predicate expression, `(< end beg)', will be true and
the text will be prepended before the previous text.  On the other
hand, if the value of the variable `end' is greater than the value of
the variable `beg', the text will be appended after the previous text.

   When the newly saved text will be prepended, then the string with
the new text will be concatenated before the old test:

     (concat string (car kill-ring))

But if the text will be appended, it will be concatenated after the old
text:

     (concat (car kill-ring) string))

   To understand how this works, we first need to review the `concat'
function.  The `concat' function links together or unites two strings
of text.  The result is a string.  For example:

     (concat "abc" "def")
          => "abcdef"

     (concat "new "
             (car '("first element" "second element")))
          => "new first element"

     (concat (car
             '("first element" "second element")) " modified")
          => "first element modified"

   We can now make sense of `kill-append': it modifies the contents of
the kill ring.  The kill ring is a list, each element of which is saved
text.  The `setcar' function actually changes the first element of this
list.  It does this by using `concat' to replace the old first element
of the kill ring (the CAR of the kill ring) with a new first element
made by concatenating together the old saved text and the newly saved
text.  The newly saved text is put in front of the old text or after
the old text, depending on whether it is in front of or after the old
text in the buffer from which it is cut.  The whole concatenation
becomes the new first element of the kill ring.

   Incidentally, this is what the beginning of my current kill ring
looks like:

     ("concatenating together" "saved text" "element" ...

The else-part of `copy-region-as-kill'
......................................

   Now, back to the explanation of `copy-region-as-kill':

   If the last command is not `kill-region', then instead of calling
`kill-append', it calls the else-part of the following code:

     (if TRUE-OR-FALSE-TEST
         WHAT-IS-DONE-IF-TEST-RETURNS-TRUE
       ;; else-part
       (setq kill-ring
             (cons (buffer-substring beg end) kill-ring))
       (if (> (length kill-ring) kill-ring-max)
           (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))

   The `setq' line of the else-part sets the new value of the kill ring
to what results from adding the string being killed to the old kill
ring.

   We can see how this works with a little example:

     (setq example-list '("here is a clause" "another clause"))

After evaluating this expression with `C-x C-e', you can evaluate
`example-list' and see what it returns:

     example-list
          => ("here is a clause" "another clause")

Now, we can add a new element on to this list by evaluating the
following expression:

     (setq example-list (cons "a third clause" example-list))

When we evaluate `example-list', we find its value is:

     example-list
          => ("a third clause" "here is a clause" "another clause")

Thus, the third clause was added to the list by `cons'.

   This is exactly similar to what the `setq' and `cons' do in the
function, except that `buffer-substring' is used to pull out a copy of
a region of text and hand it to the `cons'.  Here is the line again:

     (setq kill-ring (cons (buffer-substring beg end) kill-ring))

   The next segment of the else-part of `copy-region-as-kill' is
another `if' clause.  This `if' clause keeps the kill ring from growing
too long.  It reads as follows:

     (if (> (length kill-ring) kill-ring-max)
         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))

   This code checks whether the length of the kill ring is greater than
the maximum permitted length.  This is the value of `kill-ring-max'
(which is 30, by default).  If the length of the kill ring is too long,
then this code sets the last element of the kill ring to `nil'.  It
does this by using two functions, `nthcdr' and `setcdr'.

   We looked at `setcdr' earlier (see `setcdr').  It sets
the CDR of a list, just as `setcar' sets the CAR of a list.  In this
case, however, `setcdr' will not be setting the `cdr' of the whole kill
ring; the `nthcdr' function is used to cause it to set the `cdr' of the
next to last element of the kill ring--this means that since the `cdr'
of the next to last element is the last element of the kill ring, it
will set the last element of the kill ring.

   The `nthcdr' function works by repeatedly taking the CDR of a
list--it takes the CDR of the CDR of the CDR ...  It does this N times
and returns the results.

   Thus, if we had a four element list that was supposed to be three
elements long, we could set the CDR of the next to last element to
`nil', and thereby shorten the list.

   You can see this by evaluating the following three expressions in
turn.  First set the value of `trees' to `(maple oak pine birch)', then
set the CDR of its second CDR to `nil' and then find the value of
`trees':

     (setq trees '(maple oak pine birch))
          => (maple oak pine birch)

     (setcdr (nthcdr 2 trees) nil)
          => nil

     trees
          => (maple oak pine)

(The value returned by the `setcdr' expression is `nil' since that is
what the CDR is set to.)

   To repeat, in `copy-region-as-kill', the `nthcdr' function takes the
CDR a number of times that is one less than the maximum permitted size
of the kill ring and sets the CDR of that element (which will be the
rest of the elements in the kill ring) to `nil'.  This prevents the
kill ring from growing too long.

   The next to last line of the `copy-region-as-kill' function is

     `(setq this-command 'kill-region)'

This line is not part of either the inner or the outer `if' expression,
so it is evaluated every time `copy-region-as-kill' is called.  Here we
find the place where `this-command' is set to `kill-region'.  As we saw
earlier, when the next command is given, the variable `last-command'
will be given this value.

   Finally, the last line of the  `copy-region-as-kill' function is:

     (setq kill-ring-yank-pointer kill-ring)

   The `kill-ring-yank-pointer' is a global variable that is set to be
the `kill-ring'.

   Even though the `kill-ring-yank-pointer' is called a `pointer', it
is a variable just like the kill ring.  However, the name has been
chosen to help humans understand how the variable is used.  The
variable is used in functions such as `yank' and `yank-pop' (see
Yanking Text Back).

   This leads us to the code for bringing back text that has been cut
out of the buffer--the yank commands.  However, before discussing the
yank commands, it is better to learn how lists are implemented in a
computer.  This will make clear such mysteries as the use of the term
`pointer'.

Review
======

   Here is a brief summary of some recently introduced functions.

`car'
`cdr'
     `car' returns the first element of a list; `cdr' returns the
     second and subsequent elements of a list.

     For example:

          (car '(1 2 3 4 5 6 7))
               => 1
          (cdr '(1 2 3 4 5 6 7))
               => (2 3 4 5 6 7)

`cons'
     `cons' constructs a list by prepending its first argument to its
     second argument.

     For example:

          (cons 1 '(2 3 4))
               => (1 2 3 4)

`nthcdr'
     Return the result of taking `cdr' `n' times on a list.  The `rest
     of the rest' as it were.

     For example:

          (nthcdr 3 '(1 2 3 4 5 6 7))
               => (4 5 6 7)

`setcar'
`setcdr'
     `setcar' changes the first element of a list; `setcdr' changes the
     second and subsequent elements of a list.

     For example:

          (setq triple '(1 2 3))

          (setcar triple '37)

          triple
               => (37 2 3)

          (setcdr triple '("foo" "bar"))

          triple
               => (37 "foo" "bar")

`progn'
     Evaluate each argument in sequence and then return the value of the
     last.

     For example:

          (progn 1 2 3 4)
               => 4

`save-restriction'
     Record whatever narrowing is in effect in the current buffer, if
     any, and restore that narrowing after evaluating the arguments.

`search-forward'
     Search for a string, and if the string is found, move point.

     Takes four arguments:

       1. The string to search for.

       2. Optionally, the limit of the search.

       3. Optionally, what to do if the search fails, return `nil' or an
          error message.

       4. Optionally, how many times to repeat the search; if negative,
          the search goes backwards.

`kill-region'
`delete-region'
`copy-region-as-kill'
     `kill-region' cuts the text between point and mark from the buffer
     and stores that text in the kill ring, so you can get it back by
     yanking.

     `delete-region' removes the text between point and mark from the
     buffer and throws it away.  You cannot get it back.

     `copy-region-as-kill' copies the text between point and mark into
     the kill ring, from which you can get it by yanking.  The function
     does not cut or remove the text from the buffer.

Searching Exercises
===================

   * Write an interactive function that searches for a string.  If the
     search finds the string, leave point after it and display a message
     that says "Found!".  (Do not use `search-forward' for the name of
     this function; if you do, you will overwrite the existing version
     of `search-forward' that comes with Emacs.  Use a name such as
     `test-search' instead.)

   * Write a function that prints the third element of the kill ring in
     the echo area, if any; if the kill ring does not contain a third
     element, print an appropriate message.

   * As of version 19.29, `copy-region-as-kill' no longer sets
     `this-command'.  What are the consequences of this change?  What
     do you suppose motivated it?

How Lists are Implemented
*************************

   In Lisp, atoms are recorded in a  straightforward fashion; if the
implementation is not straightforward in practice, it is, nonetheless,
straightforward in theory.  The atom `rose', for example, is recorded
as the four contiguous letters `r', `o', `s', `e'.  A list, on the
other hand, is kept differently.  The mechanism is equally simple, but
it takes a moment to get used to the idea.  A list is kept using a
series of pairs of pointers.  In the series, the first pointer in each
pair points to an atom or to another list, and the second pointer in
each pair points to the next pair, or to the symbol `nil', which marks
the end of the list.

   A pointer itself is quite simply the electronic address of what is
pointed to.  Hence, a list is kept as a series of electronic addresses.

   For example, the list `(rose violet buttercup)' has three elements,
`rose', `violet', and `buttercup'.  In the computer, the electronic
address of `rose' is recorded in a segment of computer memory along
with the address that gives the electronic address of where the atom
`violet' is located; and that address (the one that tells where
`violet' is located) is kept along with an address that tells where the
address for the atom `buttercup' is located.

   This sounds more complicated than it is and is easier seen in a
diagram:

         ___ ___      ___ ___      ___ ___
        |___|___|--> |___|___|--> |___|___|--> nil
          |            |            |
          |            |            |
           --> rose     --> violet   --> buttercup

In the diagram, each box represents a word of computer memory that
holds a Lisp object, usually in the form of a memory address.  The
boxes, i.e. the addresses, are in pairs.  Each arrow points to what the
address is the address of, either an atom or another pair of addresses.
The first box is the electronic address of `rose' and the arrow points
to `rose'; the second box is the address of the next pair of boxes, the
first part of which is the address of `violet' and the second part of
which is the address of the next pair.  The very last box points to the
symbol `nil', which marks the end of the list.

   When a variable is set to a list with a function such as `setq', it
stores the address of the first box in the variable.  Thus, evaluation
of the expression

     (setq bouquet '(rose violet buttercup))

creates a situation like this:

     bouquet
          |
          |     ___ ___      ___ ___      ___ ___
           --> |___|___|--> |___|___|--> |___|___|--> nil
                 |            |            |
                 |            |            |
                  --> rose     --> violet   --> buttercup

In this case, the symbol `bouquet' holds the address of the first pair
of boxes.  Indeed, the symbol `bouquet' consists of a group of
address-boxes, one of which is the address of the printed word
`bouquet', a second of which is the address of a function definition
attached to the symbol, if any, a third of which is the address of the
first pair of address-boxes for the list `(rose violet buttercup)', and
so on.

   This same list can be illustrated in a different sort of box notation
like this:

     bouquet
      |
      |    --------------       ---------------       ----------------
      |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
       -->| rose  |   o------->| violet |   o------->| butter- |  nil |
          |       |      |     |        |      |     | cup     |      |
           --------------       ---------------       ----------------

   In an earlier section, I suggested that you might imagine a symbol as
being a chest of drawers.  The function definition is put in one drawer,
the value in another, and so on.  What is put in the drawer holding the
value can be changed without affecting the contents of the drawer
holding the function definition, and vice-versa.  Actually, what is put
in each drawer is the address of the value or function definition.  It
is as if you found an old chest in the attic, and in one of its drawers
you found a map giving you directions to where the buried treasure lies.

   (In addition to its name, symbol definition, and variable value, a
symbol has a `drawer' for a "property list" which can be used to record
other information.  Property lists are not discussed here; see
Property Lists (elisp).)

   Here is a fanciful representation:

     Chest of Drawers             Contents of Drawers

              ---------------------
             |                     |
             |    symbol name      |             bouquet
             |                     |
              ---------------------
             |                     |
             |  symbol definition  |             [none]
             |                     |
              ---------------------
             |                     |
             |   variable value    |             (rose violet buttercup)
             |                     |
              ---------------------
             |                     |
             |   property list     |             [not described here]
             |                     |
              ---------------------
             |/                   \|

   If symbol is set to the CDR of a list, the list itself is not
changed; the symbol simply has an address further down the list.  (In
the jargon, CAR and CDR are `non-destructive'.)  Thus, evaluation of
the following expression

     (setq flowers (cdr bouquet))

produces this:

     bouquet        flowers
       |              |
       |     ___ ___  |     ___ ___      ___ ___
        --> |   |   |  --> |   |   |    |   |   |
            |___|___|----> |___|___|--> |___|___|--> nil
              |              |            |
              |              |            |
               --> rose       --> violet   --> buttercup

The value of `flowers' is `(violet buttercup)', which is to say, the
symbol `flowers' holds the address of the pair of address-boxes, the
first of which holds the address of `violet', and the second of which
holds the address of `buttercup'.

   A pair of address-boxes is called a "cons cell" or "dotted pair".
See List Type (elisp), and Dotted Pair Notation (elisp),
for more information about cons cells and
dotted pairs.

   The function `cons' adds a new pair of addresses to the front of a
series of addresses like that shown above.  For example, evaluating the
expression

     (setq bouquet (cons 'lilly bouquet))

produces:

     bouquet                       flowers
       |                             |
       |     ___ ___        ___ ___  |     ___ ___       ___ ___
        --> |   |   |      |   |   |  --> |   |   |     |   |   |
            |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
              |              |              |             |
              |              |              |             |
               --> lilly      --> rose       --> violet    --> buttercup

However, this does not change the value of the symbol `flowers', as you
can see by evaluating the following,

     (eq (cdr (cdr bouquet)) flowers)

which returns `t' for true.

   Until it is reset, `flowers' still has the value `(violet
buttercup)'; that is, it has the address of the cons cell whose first
address is of `violet'.  Also, this does not alter any of the
pre-existing cons cells; they are all still there.

   Thus, in Lisp, to get the CDR of a list, you just get the address of
the next cons cell in the series; to get the CAR of a list, you get the
address of the first element of the list; to `cons' a new element on a
list, you add a new cons cell to the front of the list.  That is all
there is to it!  The underlying structure of Lisp is brilliantly simple!

   And what does the last address in a series of cons cells refer to?
It is the address of the empty list, of `nil'.

   In summary, when a Lisp variable is set to a value, it is provided
with the address of the list to which the variable refers.

Exercise
========

   Set `flowers' to `violet' and `buttercup'.  Cons two more flowers on
to this list and set this new list to `more-flowers'.  Set the CAR of
`flowers' to a fish.  What does the `more-flowers' list now contain?

Yanking Text Back
*****************

   Whenever you cut text out of a buffer with a `kill' command in GNU
Emacs, you can bring it back with a `yank' command.  The text that is
cut out of the buffer is put in the kill ring and the yank commands
insert the appropriate contents of the kill ring back into a buffer
(not necessarily the original buffer).

   A simple `C-y' (`yank') command inserts the first item from the kill
ring into the current buffer.  If the `C-y' command is followed
immediately by `M-y', the first element is replaced by the second
element.  Successive `M-y' commands replace the second element with the
third, fourth, or fifth element, and so on.  When the last element in
the kill ring is reached, it is replaced by the first element and the
cycle is repeated.  (Thus the kill ring is called a `ring' rather than
just a `list'.  However, the actual data structure that holds the text
is a list.  See Handling the Kill Ring, for the details of
how the list is handled as a ring.)

Kill Ring Overview
==================

   The kill ring is a list of textual strings.  This is what it looks
like:

     ("some text" "a different piece of text" "yet more text")

   If this were the contents of my kill ring and I pressed `C-y', the
string of characters saying `some text' would be inserted in this
buffer where my cursor is located.

   The `yank' command is also used for duplicating text by copying it.
The copied text is not cut from the buffer, but a copy of it is put on
the kill ring and is inserted by yanking it back.

   Three functions are used for bringing text back from the kill ring:
`yank', which is usually bound to `C-y'; `yank-pop', which is usually
bound to `M-y'; and `rotate-yank-pointer', which is used by the two
other functions.

   These functions refer to the kill ring through a variable called the
`kill-ring-yank-pointer'.  Indeed, the insertion code for both the
`yank' and `yank-pop' functions is:

     (insert (car kill-ring-yank-pointer))

   To begin to understand how `yank' and `yank-pop' work, it is first
necessary to look at the `kill-ring-yank-pointer' variable and the
`rotate-yank-pointer' function.